Clarify run-sql's release resolution and Skill guidance (citation, truncation) - #3
Merged
Merged
Conversation
Testing showed the Skill's guidance wasn't clear enough: run-sql has no --release flag at all (unlike list-datasets/describe-dataset), and release selection happens by scanning the query text for schema qualifiers, not via a CLI argument - each qualifier (e.g. "26.06") is read directly as a release identifier and lazily built if needed. A single call can therefore span any number of releases just by naming them in the SQL, with no separate flag or "compare releases" step. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Rule 6 ("cite your sources") already covered showing the SQL, but was
ambiguous about *when* (didn't say "at the end") and about multi-query
turns (didn't say "every query, not just the last"). Tightened it
rather than adding a duplicate rule.
Added rule 7: nothing previously told the agent to check
data.truncated on a *successful* run-sql response - a capped result is
still ok:true, so without this an agent could silently present a
partial (first-1000-rows) result as if it were complete. Recommends
aggregating over paginating as the default strategy, with LIMIT/OFFSET
pagination as a fallback for genuine row-level-detail needs.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
project-defiant
changed the title
jdhayhurst
approved these changes
Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two rounds of Skill guidance clarifications, based on real testing:
Release resolution —
run-sqlhas no--releaseflag at all (unlikelist-datasets/describe-dataset), and release selection happens by scanning the query text for schema qualifiers, not via a CLI argument — each qualifier (e.g."26.06") is read directly as a release identifier and lazily built if needed. A single call can span any number of releases just by naming them in the SQL.SQL query citation — the existing "cite your sources" rule already asked for the SQL to be shown, but was ambiguous about when (didn't say "at the end") and about multi-query turns (didn't say "every query, not just the last one"). Tightened the existing rule rather than adding a duplicate.
Truncation handling, new — nothing previously told the agent to check
data.truncatedon a successfulrun-sqlresponse. A capped result (~1000 rows) is stillok: true, so without this an agent could silently present a partial result as if it were complete. Added guidance to prefer aggregating (COUNT,GROUP BY,TOP N) over paginating by default, withLIMIT/OFFSETpagination as an explicit fallback when the user genuinely needs row-level detail beyond 1000 rows.Docs-only change, no code changes.
Test plan
prek run --files .claude/skills/otai/SKILL.mdpasses